跳至主要內容

移動檔案或目錄 (file.move)

聲明​

操作成敗, 錯誤資訊 = file.move(來源路徑, 目標路徑 [, 模式])

參數​

  • 來源路徑
    文字型,來源檔案或目錄的絕對路徑
  • 目標路徑
    文字型,移動後的檔案或目錄的完整絕對路徑,包含目標檔名或目錄名
  • 模式 20250914+
    文字型,可選參數,移動模式。取值:
    • 空字串或省略:預設模式(no-clobber),當目標已存在時回傳失敗
    • "overwrite" 或 "o":覆蓋模式,直接替換已存在的目標(已存在的目標會被刪除)
    • "merge" 或 "m":合併模式(僅用於目錄),保留目標中已存在的檔案
    • "overwrite-merge" 或 "om"/"mo":覆蓋合併模式,合併目錄但覆蓋同名檔案

回傳值​

  • 操作成敗
    布林型,操作成功回傳 true,操作失敗回傳 false
  • 錯誤資訊
    文字型,操作失敗時的錯誤資訊

說明​

將 來源路徑 指向的檔案或目錄移動為 目標路徑;在同一目錄下更名即為重新命名
該函式是「移動為」語義,不是「移動進」語義。目標路徑 指定最終的檔案或目錄,不會自動追加來源檔名或目錄名;即使目標已存在且為目錄,或者目標路徑以 / 結尾,也不會將來源檔案或目錄放入該目錄中
例如,要把 /a/b/c 移動到 /d/e/ 中並保留名稱 c,目標路徑應寫為 /d/e/c,不能只寫 /d/e/
目標已存在時,按 模式 參數處理:預設模式回傳失敗,覆蓋模式替換目標本身,目錄合併模式則將來源目錄內容合併到目標目錄
關鍵詞:重新命名檔案、重新命名目錄、重新命名資料夾、移動檔案、移動目錄、移動資料夾
該函式在 20250313 以後的版本方可使用

範例​

ok, err = file.move(XXT_SCRIPTS_PATH..'/1.zip', XXT_SCRIPTS_PATH..'/2.zip')
if not ok then
sys.alert('移動失敗:'..err)
end

注:上述程式碼中使用了非本章函式 sys.alert

移動到另一個目錄並保留名稱​

-- 假設 /d/e 是已存在的目錄,/d/e/c 尚不存在
file.move('/a/b/c', '/d/e/c') -- 正確:將 c 移動為 /d/e/c

-- 以下為獨立的錯誤寫法範例,目標是 e 本身,不是 e 目錄中的 c
-- file.move('/a/b/c', '/d/e/') -- 預設模式下因目標已存在而失敗

-- 覆蓋模式會替換 e 本身,不會生成 /d/e/c(20250914+)
-- file.move('/a/b/c', '/d/e/', 'overwrite')

封裝「移動進目錄」函式​

以下為自訂封裝範例,需要 20250914 以後的版本。目標目錄須已存在,函式會保留來源檔案或目錄名,並將可選的 mode 參數傳給 file.move。發生同名衝突時,仍按指定模式處理。

local function file_move_into(src_path, dst_dir, mode)
if file.exists(dst_dir) ~= "directory" then
return false, "Target is not a directory"
end

local name, err = file.path.last_component(src_path)
if not name then
return false, err
end
-- 避免將目標目錄本身或其父目錄作為最終目標。
if name == "" or name == "/" or name == "." or name == ".." then
return false, "Source path must end with a file or directory name"
end

local dst_path, path_err = file.path.add_component(dst_dir, name)
if not dst_path then
return false, path_err
end
return file.move(src_path, dst_path, mode)
end

-- 假設 /d/e 是已存在的目錄,將 c 移動為 /d/e/c
local ok, err = file_move_into("/a/b/c", "/d/e/")
if not ok then
print("移動失敗:"..err)
end

-- 如需替換 /d/e/c,可在呼叫時指定覆蓋模式:
-- file_move_into("/a/b/c", "/d/e/", "overwrite")

注:上述程式碼使用了 file.exists、file.path.last_component 和 file.path.add_component。